home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_200 / 225_01 / z1.doc < prev    next >
Text File  |  1987-06-08  |  9KB  |  161 lines
  1. HEADER:         ;
  2. TITLE:          ;
  3. VERSION:        ;
  4.  
  5. DESCRIPTION:    Describes Z1.COM in terms of changes to Z80MR.COM;
  6.  
  7. KEYWORDS:       ;
  8. SYSTEM:         CP/M-80, V2.2;
  9. FILENAME:       Z1.DOC;
  10. WARNINGS:       Describes only the new features.  Original Z80MR and
  11.                 associated doc files available on disk #B25 from Micro
  12.                 Cornucopia Magazine;
  13.  
  14. SEE-ALSO:       Z1.COM;
  15. AUTHORS:        Neil Koozer;
  16. COMPILERS:      ;
  17.  
  18. Z1.DOC   by   Neil R. Koozer, Kellogg Star Rt. Box 125, Oakland, OR 97462
  19.  
  20.      Z1.COM  is  my own modification of Z80MR.COM.   The original  Z80MR  and 
  21. associated  DOC files are on disk #B25 from Micro Cornucopia  Magazine,  P.O. 
  22. box 223, Bend, OR 97709.  The following is a description of the changes:
  23.  
  24. LIST  C.   Using  the  C option causes the assembler to produce  a  COM  file 
  25. directly  without producing a HEX file.   In this mode,  the gaps left by ORG 
  26. and  DS statements are filled with 00's except at the beginning of the  file.  
  27. If  you  put a bunch of buffers at the beginning,  they will not add  to  the 
  28. stored code in the COM file.  See the source listing Z1.AZM for an example of 
  29. using an up-loader to put the code where it runs.
  30.  
  31. LIST P.  Using the P option invokes single-pass operation.  In order for LIST 
  32. P  to be recognized,  it must be in the very first line of the  source  file.  
  33. The  regular  labels  can't  be used for  forward  reference  in  single-pass 
  34. operation,  so  the  source  needs  to be arranged  like  a  Pascal  program.  
  35. Subroutines,  jump destinations,  and data objects need to be defined  before 
  36. they are used.   In the few places where this can not be done, we use psuedo-
  37. labels (see below) for forward references.
  38.  
  39. PSUEDO-LABELS.   These are abbreviated symbols intended for use in very short 
  40. jumps and for forward references in single pass operation.  They are actually 
  41. embellished  versions of the $ symbol.   They consist of two characters,  the 
  42. first of which is $.
  43.  
  44. $0 thru $9,  $%,  $!, $@, $? are backward symbols and work almost the same as 
  45. regular symbols:
  46.           $0   LD A,B         ;this line same as    $0 DEFL $
  47.                DJNZ $0        ;                        LD A,B  
  48.                LD B,85
  49.           $0   CALL DOSUMPN
  50.                DJNZ $0
  51. These symbols don't go into the symbol table,  so there is no search time  to 
  52. find  them.   Using  these  symbols prevents a lot of nonsense  symbols  from 
  53. bloating  the  symbol  table,  thereby making large  programs  assemble  more 
  54. efficiently.   These  symbols can be redefined at will and can be  referenced 
  55. any number of times after each definition.
  56.  
  57. $A thru $Z are forward symbols:
  58.                JR NZ,$A       ;symbol $A initialized here
  59.                LD A,45
  60.                JR $B
  61.           $A   LD A,73        ;symbol $A resolved here
  62.           $B   LD (THERE),A
  63.                ....
  64. Each  of  these symbols can only be used (or initialized) once  until  it  is 
  65. resolved.   After being resolved,  it is free to be used again.   Since these 
  66. symbols must toggle between active (initialized) and inactive (resolved), the 
  67. assembler can recognize an unbalance and issue an error code.   A 'W' in  the 
  68. left  margin  denotes  such a phase error.   If two lines must  make  forward 
  69. reference to the same spot, then two psuedo labels can be used:
  70.                JR Z,$C
  71.                CP 'S'
  72.                JR Z,$D
  73.                ...
  74.           $C
  75.           $D   LD A,B
  76. The  psuedo-labels  can  be used in expressions,  but the  forward  varieties 
  77. suffer  the  same  restrictions  as  external  symbols.   The  expression  is 
  78. restricted  to  effectively  adding  a forward symbol  to  the  rest  of  the 
  79. expression.   The  'E'  error code shows up for invalid  expressions.   Since 
  80. these  symbols  do not nest,  there are two separate symbols with  a  nesting 
  81. property,  $$ for backward and $_ for forward.   They are primarily for  jump 
  82. tables:
  83.           $$   <routine1>
  84.           $$   <routine2>
  85.           $$   <routine3>
  86.                ...
  87.           JMPTABL DW $$,$$,$$,...
  88. Another usage:
  89.                LD B,0
  90.           $$   PUSH BC
  91.                LD B,0
  92.           $$   DJNZ $$        ;this one references the second $$
  93.                POP BC
  94.                DJNZ $$        ;this one references the first $$
  95. Because  of  their  nesting property,  the symbols $$ and $_ can be  used  in 
  96. macros, thereby preventing macros from filling the symbol table with nonsense 
  97. symbols.   The maximum nesting depth of $$ and $_ is set by a couple of EQU's 
  98. at the beginning of the source code of the assembler.  They are presently set 
  99. at 40 for $$ and 10 for $_.
  100.      The forward psuedo-labels only work when outputting a COM file.   If you 
  101. want to make a HEX file,  you have to use two-pass operation if there are any 
  102. forward references.
  103.  
  104. LIST  and  *LIST  are  now  the  same.   They both  will  accept  a  list  of 
  105. single_character options as well as the words ON and OFF.
  106.           *LIST A,B,ON
  107.                LIST A,ON,B
  108.                LIST A,B,S     ;all three are equivalent.
  109. It is best to keep the ON or OFF at the end of the list because the statement
  110.                LIST A,OFF,B
  111. will also turn off B.
  112.  
  113. INTERNAL CHANGES.   In order to resolve forward references during single-pass 
  114. assembly  I  changed the buffering of the object output to  use  demand-paged 
  115. virtual  memory.   To speed up the handling of text,  I changed the buffering 
  116. method  for the input,  include,  and listing files.   The method essentially 
  117. adds some auxilliary space to the length of the buffer so that you never have 
  118. to worry about the end of the buffer occuring in the line you are working on.  
  119. This obviates many operations and allows some operations to be done with  Z80 
  120. block  move instructions.   To speed up symbol search,  I replaced the linear 
  121. search  with a binary search.   When symbols are created,  they are  inserted 
  122. into the table alphabetically.   At first thought,  this seemed like too much 
  123. moving,  but it is very mush faster than sorting and makes the binary  search 
  124. possible during the first pass.   To speed up the search for mnemonics, I put 
  125. them all into a 'state machine'.  This is faster than a binary search because 
  126. it never has to start over at the beginning of the next word.  It essentially 
  127. does a multi-way branch on each character.   For example,  in the words DEFL, 
  128. DEFS,  DEFW,  and  DEFM,  after getting through DEF,  it only uses the fourth 
  129. character  to  determine if it has one of these words.   It doesn't  have  to 
  130. go  through DEF again.   The 'state machine' is also fast because there is no 
  131. looping involved;  it consists entirely of compares and branches.  I took the 
  132. register  names  out of the symbol table and put them into their  own  little 
  133. state machine.  Ditto for the flag-condition mnemonics.
  134.  
  135. SPEED.   This  thing  assembles  itself to a COM file in 15.8 sec on  my  Z80 
  136. system (3.68 Mhz, 1 wait, RAM disk).  This is around 17 times faster than the 
  137. original Z80MR can assemble itself and be LOADed.  For another comparison, it 
  138. takes  the  CPM LOAD program 9 seconds to translate the equivalent  HEX  file 
  139. into a COM file.
  140.  
  141. OTHER NOTES.   If you run this assembler you may notice in the listing output 
  142. that  the  addresses are printed in 24-bit format.   This is because  I  have 
  143. begun  to  convert the assembler to a 32000 cross  assembler.   It  currently 
  144. handles  the program counter as a 32-bit value and is able to make COM  files 
  145. larger than 64k (if you can train your Z80 to use them).   The  psuedo-labels 
  146. store  32-bit values,  but the regular symbols still use only 16-bit  values.  
  147. If  you  look  at the source listing,  you will notice that  some  lines  are 
  148. indented  with a space and some are indented with a tab.   This is because  I 
  149. have  started using the space-only indenting to indicate which lines  I  have 
  150. written  or  changed.   I  hope  that I didn't mess up any  of  the  original 
  151. features, but I have not done enough testing to be sure.  I can't really test 
  152. the